Technotools/Technotools (Chestnut CD-ROM)(1993).ISO/lang_oth/forchek1/forchek.hlp

Text File | 1991-10-28 | 16KB | 293 lines

1 FORCHEK
 Fortran program checker.
2 Introduction


      Forchek (short  for  Fortran  checker)  is  designed  to  detect
 certain errors in a Fortran program that a compiler usually does not.
 Forchek is not primarily  intended  to  detect  syntax  errors.   Its
 purpose  is  to assist the user in finding semantic errors.  Semantic
 errors are legal in the Fortran language  but  are  wasteful  or  may
 cause  incorrect  operation.   For example, variables which are never
 used  may  indicate  some  omission  in  the  program;  uninitialized
 variables  contain  garbage  which  may cause incorrect results to be
 calculated; and variables which are not declared  may  not  have  the
 intended  type.  Forchek is intended to assist users in the debugging
 of their Fortran program.  It is not intended  to  catch  all  syntax
 errors.   This  is  the  function  of  the  compiler.  Prior to using
 Forchek, the user should verify that the program compiles correctly.

      For more detailed information, consult the documentation.
2 Invoking_Forchek

 Forchek is invoked through a command of the form:

     $ forchek [/option /option ...] filename [filename ...]

 (The brackets indicate something which  is  optional.   The  brackets
 themselves  are  not  actually  typed.) Here options are command-line
 switches or settings, which control the operation of the program  and
 the  amount of information that will be printed out.  If no option is
 specified, the default action is to print error  messages,  warnings,
 and  informational  messages,  but  not the program listing or symbol
 tables.

      Each option begins with the '/' character.  (Forchek also allows
 the '-' character to be used.)
2 Files


      When giving a name of an input file, the extension is  optional.
 If  no extension is given, Forchek will first look for a project file
 with extension '.prj' and will use that if it exists.  If  not,  then
 Forchek will look for a Fortran source file with the extension '.for'
 for VMS systems, '.f' for Unix systems.  More than one file name  can
 be  given to Forchek, and it will process the modules in all files as
 if they were in a single file.

      If no filename is  given,  Forchek  will  read  input  from  the
 standard input.
2 Options

 Forchek options fall into two categories:  switches, which are either
 true  or  false,  and settings, which have a numeric or string value.
 The name of a switch can be preceded by 'no' to turn  it  off:   e.g.
 /nousage  would turn off the warnings about variable usage.  Only the
 first 3 characters of an option name (not counting the '/')  need  be
 provided.
3 /columns=n
 Set maximum line length to n columns.  (Beyond this is ignored.) This
 setting  is  provided to allow checking of programs which may violate
 the Fortran standard limit of 72 columns for the length  of  a  line.
 According to the standard, all characters past column 72 are ignored.
 This setting does not affect the reporting of overlength lines  under
 the /f77 option.  Max is 132.  Default = 72.
3 /common=n
 This setting varies the strictness  of  checking  of  common  blocks.
 Level  3 is the strictest:  it requires that in each declaration of a
 given common block, corresponding variables agree in  data  type  and
 (if  arrays)  size  and number of dimensions.  Levels 1 and 2 require
 only that corresponding memory locations agree  in  data  type.   The
 difference between Levels 1 and 2 is that Level 2 warns if the blocks
 are not equal in total length, while  Level  1  does  not.   Level  0
 suppresses all checking.  Default = 3.
3 /declare
 If this flag is set, all identifiers whose datatype is  not  declared
 in  each  module  will be listed.  This flag is useful for helping to
 find misspelled variable names, etc.  The same listing will be  given
 if the module contains an IMPLICIT NONE statement.  Default = no.
3 /division
 This switch is provided to help users spot potential division by zero
 problems.   If  this  switch  is selected, every division except by a
 constant  will  be  flagged.   (It  is  assumed  that  the  user   is
 intelligent  enough  not  to  divide  by a constant which is equal to
 zero!) Default = no.
3 /extern
 Causes Forchek to report  whether  any  subprograms  invoked  by  the
 program  are  never defined, or are multiply defined.  Ordinarily, if
 Forchek is being run on a complete  program,  each  subprogram  other
 than  the  intrinsic  functions  should be defined once and only once
 somewhere.  Turn off this switch if you just want to check  a  subset
 of  files  which  form part of a larger complete program, or to check
 all at once a number of unrelated files which might each  contain  an
 unnamed main program.  Subprogram arguments will still be checked for
 correctness.  Default = yes.
3 /f77
 Use this flag to catch language extensions which violate the  Fortran
 77  standard.   Such  extensions  may  cause  your  program not to be
 portable.  Examples include the use of underscores in variable names;
 variable  names  longer  than  six characters; statement lines longer
 than 72 characters; and nonstandard statements such  as  the  DO  ...
 ENDDO  structure.   Forchek  does  not report on the use of lowercase
 letters.  Default=no.
3 /library
 This switch is used when a number of subprograms are contained  in  a
 file,  but  not  all  of them are used by the application.  Normally,
 Forchek warns you if any subprograms  are  defined  but  never  used.
 This switch will suppress these warnings.  Default = no.
3 /linebreak
 Normally, when scanning a statement which is continued onto the  next
 line,  Forchek  treats the end of the line as a space.  This behavior
 is the same as for Pascal and C, and also corresponds to  how  humans
 normally  would  read  and write programs.  However, occasionally one
 would like to use Forchek to check a program in which identifiers and
 keywords  are  split  across  lines,  for instance programs which are
 produced using a preprocessor.  Choosing the option /nolinebreak will
 cause Forchek to skip over the end of line and also any leading space
 on the continuation line (from the continuation mark up to the  first
 nonspace character).  Default = yes, i.e.  treat linebreaks as space.

      Note  that  in  nolinebreak  mode,  if  token  pairs   requiring
 intervening  space  (for  instance, GOTO 100) are separated only by a
 linebreak, they will be rejoined.

      Also, tokens requiring more than one character of lookahead  for
 the  resolution  of  ambiguities  must not be split across lines.  In
 particular, a complex constant may not be split across a line.
3 /list
 Specifies that a listing of the Fortran program is to be printed  out
 with  line  numbers.   If Forchek detects an error, the error message
 follows the program line with a caret (^) specifying the location  of
 the  error.   If  no source listing was requested, Forchek will still
 print  out  any  line  containing  an  error,  to  aid  the  user  in
 determining where the error occurred.  Default = no.
3 /novice=n
 This setting controls certain messages  about  conditions  which  are
 likely  to  be  errors  for  novice  programmers, but which are often
 intentional  by  more  sophisticated  programmers.   Some  of   these
 warnings  deal with cases in which Forchek suspects that what appears
 to be a function is intended to be an array, which the user forgot to
 declare in a DIMENSION statement.  Since a function invocation and an
 array reference  are  identical  in  syntax,  undeclared  arrays  are
 interpreted  by  the  Fortran  compiler  and by Forchek as functions.
 Novice users  are  often  confused  by  the  messages  which  result.
 Forchek attempts to remedy this confusion.  Default level = 1.

      The novice levels are given below.  The warning corresponding to
 each  number will be suppressed if the novice level is set to greater
 than that value.

         1.  Warn if arrays passed as arguments to a subprogram do not
            match  the corresponding dummy arguments in both number of
            dimensions and size.  Exception:  if the declared size  of
            the  dummy array is 1 or if it is dimensioned with a dummy
            variable, only the number of dimensions will be checked.

         2.  Warn the user if any argument of a subprogram appears  to
            be  a  function.   This warning is suppressed if the dummy
            argument is declared in  an  EXTERNAL  statement.   Novice
            programmers  seldom  pass  functions  as  arguments  of  a
            subprogram, so it is more likely that such an argument was
            intended to be an array, but was not dimensioned.

         3.  If a function was invoked but never defined,  advise  the
            user  that  it  may be an array which was not dimensioned.
            This warning is suppressed if the function is declared  in
            an  EXTERNAL  or  INTRINSIC statement in any module of the
            program.  This warning is  completely  suppressed  by  the
            /noextern option.

         4.  Warn if  a  function  has  side  effects:   i.e.   if  it
            modifies  any  of its arguments, or modifies a variable in
            common.  Ideally, a function has no side effects, and acts
            only  by computing a value based on its arguments, whereas
            a subroutine normally acts through side effects.  Advanced
            programmers  sometimes  wish  to combine the features of a
            subroutine and a function in a single module.
3 /output=filename
 This setting is provided for convenience  on  systems  which  do  not
 allow easy redirection of output from programs.  When this setting is
 given, the output which normally appears on the screen will  be  sent
 instead to the named file.  Note, however, that operational errors of
 Forchek itself (e.g.  out of space or cannot open file) will still be
 sent  to the screen.  The extension for the filename is optional, and
 if no extension is given, the extension .lis will be used.
3 /portability
 Forchek will give warnings for  a  variety  of  non-portable  usages.
 These  include  the use of tabs except in comments or inside strings,
 the use of hollerith constants, and the equivalencing of variables of
 different  data  types.   This  option  does not produce warnings for
 violations  of  the  Fortran  77  standard,  which  may  also   cause
 portability  problems.  To catch those, use the /f77 option.  Default
 = no.
3 /project
 Forchek will create a project file from  each  source  file  that  is
 input  while  this flag is in effect.  The project file will be given
 the same name as the input file,  but  with  the  extension  '.f'  or
 '.for'  replaced  by  '.prj'.   (If input is from standard input, the
 project file is named forchek.prj.) Default = no.

 A project file contains a summary  of  information  from  the  source
 file,  for  use in checking agreement among function, subroutine, and
 common block usages in other files.  It allows incremental  checking,
 which  saves  time  whenever you have a large set of files containing
 shared subroutines, most of which seldom change.  You can run Forchek
 once  on  each  file with the /project flag set, creating the project
 files.  Usually you would also set the /library and  /noextern  flags
 at this time, to suppress messages relating to consistency with other
 files.  Only error messages pertaining to each file by itself will be
 printed at this time.  Thereafter, run Forchek without these flags on
 all the project  files  together,  to  check  consistency  among  the
 different  files.  All messages internal to the individual files will
 now be omitted.  Only when a file is altered will a new project  file
 need to be made for it.

      The information saved  in  the  project  file  consists  of  all
 subprogram  declarations,  all subprogram invocations not resolved by
 declarations in the same file, and one instance of each common  block
 declaration.    Thus  project  files  contain  only  information  for
 checking agreement between files.  This means that a project file  is
 of  no  use if all modules of the complete program are contained in a
 single file.

      Naturally, when the /project flag is set, Forchek will not  read
 project files as input.
3 /sixchar
 One of the goals of the Forchek program is to  help  users  to  write
 portable Fortran programs.  One potential source of nonportability is
 the use of variable names that are longer than six characters.   Some
 compilers  just  ignore  the  extra  characters.  This behavior could
 potentially lead to two different variables being considered  as  the
 same.  For instance, variables named AVERAGECOST and AVERAGEPRICE are
 the same in the first six characters.  If  you  wish  to  catch  such
 possible conflicts, use this flag.  Default = no.
3 /symtab
 A symbol table will be printed  out  for  each  module,  listing  all
 identifiers  mentioned  in  the module.  This table gives the name of
 each variable, its datatype, and the number of dimensions for arrays.
 An  asterisk  (*)  indicates  that  the  variable has been implicitly
 typed, rather than  being  named  in  an  explicit  type  declaration
 statement.   The  table  also  lists  all  subprograms invoked by the
 module, all common blocks declared, etc.  Default = no.
3 /usage
 This switch is  on  by  default.   It  causes  Forchek  to  list  all
 variables which may be used before they are initialized, or which are
 given a value but never subsequently used, or which are declared  but
 never  used.   Sometimes Forchek makes a mistake about this.  Usually
 it errs on the side of giving a warning where no problem exists,  but
 in rare cases it will fail to warn where the problem does exist.  See
 the section on bugs for examples.  If variables are equivalenced, the
 rule  used by Forchek is that a reference to any variable implies the
 same reference to all variables it is  equivalenced  to.   Default  =
 yes.
3 /verbose
 This option is on by default.  Turning it off reduces the  amount  of
 output  relating to normal operation, so that error messages are more
 apparent.  This option is provided for the convenience of  users  who
 are  checking  large suites of files.  The eliminated output includes
 the names of project files, and the message reporting that no  syntax
 errors  were  found.   (Some  of this output is turned back on by the
 /list and /symtab options.) Default = yes.
2 Changing_the_defaults

      Forchek includes a mechanism for changing the default values  of
 all  options  by defining environment variables.  When Forchek starts
 up, it looks in its environment for any  variables  whose  names  are
 composed  by  prefixing  the  string  "FORCHEK_"  onto the uppercased
 version of the option name (the quote  marks  are  not  part  of  the
 name.)  If such a variable is found, its value is used to specify the
 default for the corresponding switch or  setting.   In  the  case  of
 settings (for example, the novice level) the value of the environment
 variable is read as the  default  setting  value.   In  the  case  of
 switches,  the  default  switch will be taken as true or "YES" unless
 the environment variable has the value "0" or "NO" (again, the quotes
 are  not  part  of  the value).  Of course, command-line options will
 override these defaults the same way as they  override  the  built-in
 defaults.

      Note that the environment variable name must be constructed with
 the  full-length  option  name,  which  must  be  in  uppercase.  For
 example, to make Forchek print a source listing by default,  set  the
 environment variable "FORCHEK_LIST" to "1" or "YES" or anything other
 than "0" or "NO".  The names "FORCHEK_LIS" (not the full option name)
 or  "forchek_list"  (lower case) would not be recognized.  The way to
 set the environment variables on the VAX/VMS system is by  using  the
 DEFINE  command.   For  example,  to  set the default /list switch to
 "YES", give the command

     $ DEFINE FORCHEK_LIST 1